home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kio / authinfo.h next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  9.3 KB  |  321 lines
  1. /*
  2.  *  This file is part of the KDE libraries
  3.  *  Copyright (C) 2000-2001 Dawit Alemayehu <adawit@kde.org>
  4.  *
  5.  *  This library is free software; you can redistribute it and/or
  6.  *  modify it under the terms of the GNU Library General Public
  7.  *  License as published by the Free Software Foundation; either
  8.  *  version 2 of the License, or (at your option) any later version.
  9.  *
  10.  *  This library is distributed in the hope that it will be useful,
  11.  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.  *  Library General Public License for more details.
  14.  *
  15.  *  You should have received a copy of the GNU Library General Public License
  16.  *  along with this library; see the file COPYING.LIB.  If not, write to
  17.  *  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18.  *  Boston, MA 02110-1301, USA.
  19.  */
  20.  
  21. #ifndef __KIO_AUTHINFO_H
  22. #define __KIO_AUTHINFO_H
  23.  
  24. #include <qmap.h>
  25. #include <qvaluelist.h>
  26. #include <kurl.h>
  27.  
  28.  
  29. namespace KIO {
  30.  
  31. /**
  32.  * This class is intended to make it easier to prompt for, cache
  33.  * and retrieve authorization information.
  34.  *
  35.  * When using this class to cache, retrieve or prompt authentication
  36.  * information, you only need to set the necessary attributes. For
  37.  * example, to check whether a password is already cached, the only
  38.  * required information is the URL of the resource and optionally
  39.  * whether or not a path match should be performed.  Similarly, to
  40.  * prompt for password you only need to optionally set the prompt,
  41.  * username (if already supplied), comment and commentLabel fields.
  42.  *
  43.  * <em>SPECIAL NOTE:</em> If you extend this class to add additional
  44.  * parameters do not forget to overload the stream insertion and
  45.  * extraction operators ("<<" and ">>") so that the added data can
  46.  * be correctly serialzed.
  47.  *
  48.  * @short A two way messaging class for passing authentication information.
  49.  * @author Dawit Alemayehu <adawit@kde.org>
  50.  */
  51. class KIO_EXPORT AuthInfo
  52. {
  53.     KIO_EXPORT friend QDataStream& operator<< (QDataStream& s, const AuthInfo& a);
  54.     KIO_EXPORT friend QDataStream& operator>> (QDataStream& s, AuthInfo& a);
  55.  
  56. public:
  57.    /**
  58.     * Default constructor.
  59.     */
  60.    AuthInfo();
  61.  
  62.    /**
  63.     * Copy constructor.
  64.     */
  65.    AuthInfo( const AuthInfo& info );
  66.  
  67.    /**
  68.     * Overloaded equal to operator.
  69.     */
  70.    AuthInfo& operator=( const AuthInfo& info );
  71.  
  72.    /**
  73.     * Use this method to check if the object was modified.
  74.     * @return true if the object has been modified
  75.     */
  76.    bool isModified() const { return modified; }
  77.  
  78.    /**
  79.     * Use this method to indicate that this object has been modified.
  80.     * @param flag true to mark the object as modified, false to clear
  81.     */
  82.    void setModified( bool flag ) { modified = flag; }
  83.  
  84.    /**
  85.     * The URL for which authentication is to be stored.
  86.     *
  87.     * This field is required when attempting to cache authorization
  88.     * and retrieve it.  However, it is not needed when prompting
  89.     * the user for authorization info.
  90.     *
  91.     * This setting is @em required except when prompting the
  92.     * user for password.
  93.     */
  94.    KURL url;
  95.  
  96.    /**
  97.     * This is @em required for caching.
  98.     */
  99.    QString username;
  100.  
  101.    /**
  102.     * This is @em required for caching.
  103.     */
  104.    QString password;
  105.  
  106.    /**
  107.     * Information to be displayed when prompting
  108.     * the user for authentication information.
  109.     *
  110.     * @note If this field is not set, the authentication
  111.     *    dialog simply displays the preset default prompt.
  112.     *
  113.     * This setting is @em optional and empty by default.
  114.     */
  115.    QString prompt;
  116.  
  117.    /**
  118.     * The text to displayed in the title bar of
  119.     * the password prompting dialog.
  120.     *
  121.     * @note If this field is not set, the authentication
  122.     *    dialog simply displays the preset default caption.
  123.     *
  124.     * This setting is @em optional and empty by default.
  125.     */
  126.    QString caption;
  127.  
  128.    /**
  129.     * Additional comment to be displayed when prompting
  130.     * the user for authentication information.
  131.     *
  132.     * This field allows you to display a short (no more than
  133.     * 80 characters) extra description in the password prompt
  134.     * dialog.  For example, this field along with the
  135.     * commentLabel can be used to describe the server that
  136.     * requested the authentication:
  137.     *
  138.     *  \code
  139.     *  Server:   Squid Proxy @ foo.com
  140.     *  \endcode
  141.     *
  142.     * where "Server:" is the commentLabel and the rest is the
  143.     * actual comment.  Note that it is always better to use
  144.     * the @p commentLabel field as it will be placed properly
  145.     * in the dialog rather than to include it within the actual
  146.     * comment.
  147.     *
  148.     * This setting is @em optional and empty by default.
  149.     */
  150.    QString comment;
  151.  
  152.    /**
  153.     * Descriptive label to be displayed in front of the
  154.     * comment when prompting the user for password.
  155.     *
  156.     * This setting is @em optional and only applicable when
  157.     * the comment field is also set.
  158.     */
  159.    QString commentLabel;
  160.  
  161.    /**
  162.     * A unique identifier that allows caching of multiple
  163.     * passwords for different resources in the same server.
  164.     *
  165.     * Mostly this setting is applicable to the HTTP protocol
  166.     * whose authentication scheme explicitly defines the use
  167.     * of such a unique key.  However, any protocol that can
  168.     * generate or supply a unique id can effectively use it
  169.     * to distinguish passwords.
  170.     *
  171.     * (If you are instead interested in caching the authentication
  172.     * info for multiple users to the same server, refer to
  173.     * multipleUserCaching below)
  174.     *
  175.     * This setting is @em optional and not set by default.
  176.     */
  177.    QString realmValue;
  178.  
  179.    /**
  180.     * Field to store any extra authentication information for
  181.     * protocols that need it (ex: http).
  182.     *
  183.     * This setting is @em optional and mostly applicable for HTTP
  184.     * protocol.  However, any protocol can make use of it to
  185.     * store extra info.
  186.     */
  187.    QString digestInfo;
  188.  
  189.    /**
  190.     * Flag that, if set, indicates whether a path match should be
  191.     * performed when requesting for cached authorization.
  192.     *
  193.     * A path is deemed to be a match if it is equal to or is a subset
  194.     * of the cached path.  For example, if stored path is "/foo/bar"
  195.     * and the request's path set to "/foo/bar/acme", then it is a match
  196.     * whereas it would not if the request's path was set to "/foo".
  197.     *
  198.     * This setting is @em optional and false by default.
  199.     */
  200.    bool verifyPath;
  201.  
  202.    /**
  203.     * Flag which if set forces the username field to be read-only.
  204.     *
  205.     * This setting is @em optional and false by default.
  206.     */
  207.    bool readOnly;
  208.  
  209.    /**
  210.     * Flag to indicate the persistence of the given password.
  211.     *
  212.     * This is a two-way flag, when set before calling openPassDlg
  213.     * it makes the "keep Password" check box visible to the user.
  214.     * In return the flag will indicate the state of the check box.
  215.     * By default if the flag is checked the password will be cached
  216.     * for the entire life of the current KDE session otherwise the
  217.     * cached password is deleted right after the application using
  218.     * it has been closed.
  219.     */
  220.     bool keepPassword;
  221.  
  222. protected:
  223.     bool modified;
  224. private:
  225.     class AuthInfoPrivate* d;
  226. };
  227.  
  228. KIO_EXPORT QDataStream& operator<< (QDataStream& s, const AuthInfo& a);
  229. KIO_EXPORT QDataStream& operator>> (QDataStream& s, AuthInfo& a);
  230.  
  231. /**
  232.  * A Singleton class that provides access to passwords
  233.  * stored in .netrc files for automatic login purposes.
  234.  * This is only meant to address backward compatability
  235.  * with old automated ftp client style logins...
  236.  *
  237.  * @short An interface to the ftp .netrc files
  238.  * @author Dawit Alemayehu <adawit@kde.org>
  239.  */
  240. class KIO_EXPORT NetRC
  241. {
  242. public:
  243.  
  244.   /**
  245.    * Specifies the mode to be used when searching for a
  246.    * matching automatic login info for a given site :
  247.    *
  248.    * @li exactOnly        search entries with exact host name matches.
  249.    * @li defaultOnly      search entries that are specified as "default".
  250.    * @li presetOnly       search entries that are specified as "preset".
  251.    *
  252.    * @see lookup
  253.    */
  254.   enum LookUpMode
  255.   {
  256.       exactOnly = 0x0002,
  257.       defaultOnly = 0x0004,
  258.       presetOnly = 0x0008
  259.   };
  260.  
  261.   /**
  262.    * Contains auto login information.
  263.    * @see lookup()
  264.    */
  265.   struct AutoLogin
  266.   {
  267.     QString type;
  268.     QString machine;
  269.     QString login;
  270.     QString password;
  271.     QMap<QString, QStringList> macdef;
  272.   };
  273.  
  274.   /**
  275.    * A reference to the instance of the class.
  276.    * @return the class
  277.    */
  278.   static NetRC* self();
  279.  
  280.   /**
  281.    * Looks up the @p login information for the given @p url.
  282.    *
  283.    * @param url the url whose login information will be checked
  284.    * @param login the login information will be writte here
  285.    * @param userealnetrc if true, use $HOME/.netrc fle
  286.    * @param type the type of the login. If null, the @p url's protocol
  287.    *        will be taken
  288.    * @param mode the LookUpMode flags (ORed) for the query
  289.    */
  290.   bool lookup( const KURL& url, AutoLogin& login,
  291.                bool userealnetrc = false,
  292.                QString type = QString::null,
  293.                int mode = (exactOnly|defaultOnly) );
  294.   /**
  295.    * Reloads the auto login information.
  296.    */
  297.   void reload() { isDirty = true; }
  298.  
  299. protected:
  300.   QString extract( const char*, const char*, int& );
  301.   int openf( const QString& );
  302.   bool parse( int );
  303.  
  304. private:
  305.   NetRC();
  306.   ~NetRC();
  307.  
  308. private:
  309.   bool isDirty;
  310.  
  311.   typedef QValueList<AutoLogin> LoginList;
  312.   typedef QMap<QString, LoginList> LoginMap;
  313.   LoginMap loginMap;
  314.  
  315.   static NetRC* instance;
  316.   class NetRCPrivate;
  317.   NetRCPrivate* d;
  318. };
  319. }
  320. #endif
  321.